Implement SEP-990 Enterprise Managed OAuth #1721

BinoyOza-okta · 2025-12-04T16:29:20Z

This PR implements the client-side components of SEP-990: Enterprise Managed Authorization. It introduces the EnterpriseAuthOAuthClientProvider to handle the full token exchange flow required for Enterprise SSO, including RFC 8693 (Token Exchange) and RFC 7523 (JWT Bearer Grant).

Motivation and Context

Implements: SEP-990

To support enterprise environments where direct API keys are not compliant, the Python SDK needs to support "Managed Authorization." This implementation allows the SDK to:

Exchange Tokens: Convert an existing Identity Provider (IdP) token (e.g., OIDC ID Token or SAML Assertion) into an MCP-specific "ID-JAG" token using RFC 8693.
Authenticate: Exchange the ID-JAG token for a usable Access Token via RFC 7523.

This aligns the Python SDK with the architecture defined in the SEP-990 implementation guide.

Implementation Details

The following components have been added to src/mcp/client/auth/extensions/enterprise_managed_auth.py:

Data Models: TokenExchangeParameters and TokenExchangeResponse using Pydantic to strictly type the exchange payloads.
Client Provider: EnterpriseAuthOAuthClientProvider, which extends the base OAuthClientProvider to orchestrate the exchange logic.
ID-JAG Logic: Support for urn:ietf:params:oauth:token-type:id-jag token types.

How Has This Been Tested?

I have implemented comprehensive unit tests in tests/client/auth/test_enterprise_managed_auth_client.py using pytest and unittest.mock.

The testing suite covers the following scenarios:

Data Model Validation:
- Verified TokenExchangeParameters correctly generates requests for both OIDC ID Tokens (test_token_exchange_params_from_id_token) and SAML Assertions (test_token_exchange_params_from_saml_assertion).
- Validated enforcement of required fields (audience, resource, subject_token).
RFC 8693 Token Exchange Logic:
- Success Path: Mocked httpx to verify the correct payload structure (grant types, token types) is sent to the IdP.
- Client Authentication: Verified that client_id and client_secret are correctly injected into the request body when configured (test_exchange_token_with_client_authentication).
- Error Handling: Validated graceful handling of HTTP 400/500 errors, non-JSON error responses, and unexpected token types.
RFC 7523 JWT Bearer Grant Logic:
- Success Path: Verified the exchange of an ID-JAG token for a final Access Token.
- Metadata Checks: Ensured the flow fails appropriately if the MCP server's OAuth metadata (token endpoint) is missing.
Network Edge Cases:
- Simulated network failures (httpx.ConnectError, httpx.ReadTimeout) to ensure OAuthTokenError is raised with descriptive messages.

Breaking Changes

No.
This is an additive extension. The core OAuthClientProvider remains backward compatible. Only users specifically importing and using EnterpriseAuthOAuthClientProvider will be affected.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Dependencies: Utilizes pydantic for model validation and httpx for async requests.
Scope: As agreed, this PR includes the Client implementation (src/mcp/client/auth/extensions/).

maxisbey

Unless I was missing something,

src/mcp/client/auth/extensions/enterprise_managed_auth.py

tests/client/auth/test_enterprise_managed_auth_client.py

src/mcp/client/auth/extensions/enterprise_managed_auth.py

README.md

BinoyOza-okta · 2025-12-15T05:33:00Z

Hi @maxisbey, I have addressed all your comments. Could you please review the PR?

pcarleton · 2026-01-14T11:49:57Z

Hi @BinoyOza-okta, I owe you a review on this but won't be able to get to it until Jan 23rd while I wrap up conformance tests for SDK tiering.

To make progress in the meantime, a conformance test for this feature would be really helpful to ensure the implementations are compatible across SDKs.

Cross-linking: modelcontextprotocol/typescript-sdk#1328

Thanks for your patience!

…naged Auth support. - Written unit test cases for client and server implementation of the enterprise managed auth code.

…/extensions/enterprise_managed_auth.py 232->235, 304->307. - Resolved pre-commit errors.

…anaged auth.

…a and JWTBearerGrantRequestData. - Added snippet file for adding code to the README.md file. - Added new section in README.md file to add information regarding: "how to use the access token once you get it" and "How does this work when the client ID is expired?".

…-990) Implements comprehensive conformance testing for enterprise managed authorization flows including RFC 8693 token exchange and RFC 7523 JWT bearer grant with ID-JAG tokens. - Add 3 conformance test scenarios to client.py: * auth/enterprise-id-jag-validation - Validates ID-JAG token structure * auth/enterprise-token-exchange - Tests OIDC ID Token → ID-JAG → Access Token flow * auth/enterprise-saml-exchange - Tests SAML Assertion → ID-JAG → Access Token flow - Create enterprise_auth_server.py: * Implements RFC 8693 token exchange endpoint (/token-exchange) * Implements RFC 7523 JWT bearer grant endpoint (/oauth/token) * Provides OAuth metadata endpoint for discovery * Supports both OIDC ID tokens and SAML assertions * Issues ID-JAG tokens with proper structure (typ: oauth-id-jag+jwt) * Validates bearer tokens and provides protected MCP endpoints - Add run-enterprise-auth-with-server.sh: * Starts mock server on port 3002 * Dynamically fetches test context * Runs all 3 enterprise auth scenarios * Reports detailed test results * Cleans up servers on exit - Update conformance.yml workflow: * Add enterprise-auth-conformance job * Runs on every pull request * Marked as optional (continue-on-error: true) * Tests run in parallel with other conformance checks - Add fastapi>=0.115.0 to dev dependencies * Required for mock server implementation * Only needed for conformance testing * Update uv.lock accordingly - Fix docstring formatting in enterprise_managed_auth_client.py: * Update get_id_token_from_idp() to follow PEP 257 (D212) * Fix multi-line docstring to start summary on first line * Apply fix to both example file and README.md * Ensures all example tests pass - Minor updates to enterprise_managed_auth.py: * Improve error handling * Add validation for token exchange parameters ✅ ID-JAG Token Validation ✅ OIDC ID Token Exchange Flow ✅ SAML Assertion Exchange Flow - RFC 8693 Token Exchange (ID Token and SAML) - RFC 7523 JWT Bearer Grant - ID-JAG token structure validation - OAuth metadata discovery - Bearer token authentication - Error handling and edge cases - SEP-990: Enterprise Managed Authorization - RFC 8693: OAuth 2.0 Token Exchange - RFC 7523: JWT Profile for OAuth 2.0 Client Authentication - RFC 8707: Resource Indicators for OAuth 2.0 Run conformance tests: ```bash ./.github/actions/conformance/run-enterprise-auth-with-server.sh

BinoyOza-okta · 2026-01-30T16:47:43Z

Hi @pcarleton,
I have added the conformance test to the SDK. Can you please review the PR?

pcarleton · 2026-01-30T17:10:49Z

.github/actions/conformance/client.py

    elicitation-sep1034-client-defaults     - Elicitation with default accept callback
    auth/client-credentials-jwt             - Client credentials with private_key_jwt
    auth/client-credentials-basic           - Client credentials with client_secret_basic
+    auth/enterprise-token-exchange          - Enterprise auth with OIDC ID token (SEP-990)


these tests have been consolidated to 1, see modelcontextprotocol/conformance#110 and please update to match

pcarleton · 2026-01-30T17:13:48Z

.github/workflows/conformance.yml

+        with:
+          node-version: 24
+      - run: uv sync --frozen --all-extras --package mcp
+      - run: ./.github/actions/conformance/run-enterprise-auth-with-server.sh


this should not be necessary as the all command above should cover it.

pcarleton · 2026-01-30T17:14:06Z

.github/actions/conformance/enterprise_auth_server.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3


I think this is a standalone conformance test? Sorry if I didn't explain clearly, I meant in the conformance repo. See the link modelcontextprotocol/conformance#110 we want this to pass the tests in that repo so we know the different SDK's are implementing it similarly

pcarleton · 2026-01-30T17:18:40Z

examples/snippets/clients/enterprise_managed_auth_client.py

+                await session.initialize()
+
+                # Call tools with automatic retry on token expiration
+                result = await call_tool_with_retry(


we check the token is expired at 142, then we call with retry here. It seems like one or the other would be better. both seems redundant.

pcarleton · 2026-01-30T17:19:14Z

examples/snippets/clients/enterprise_managed_auth_client.py

+                    print(f"Resource: {resource.uri}")
+
+
+async def maintain_active_session(


what is this function for? it doesn't seem used. suggest removing it.

pcarleton · 2026-01-30T17:33:22Z

src/mcp/client/auth/extensions/enterprise_managed_auth.py

+
+        # For now, raise NotImplementedError as this requires integration
+        # with the full httpx auth flow
+        raise NotImplementedError(


could we call those methods here? without them, you can't drop this in as an OAuthClientProvider

pcarleton · 2026-01-30T17:34:35Z

src/mcp/client/auth/extensions/enterprise_managed_auth.py

+        Decoded ID-JAG claims
+
+    Note:
+        For verification, use server-side validation instead.


Let's reword this, saying "This function does not verify the JWT, instead relying on the receiving server to validate it."

pcarleton · 2026-01-30T17:36:40Z

examples/snippets/clients/enterprise_managed_auth_client.py

+    """Check if the access token has expired."""
+    if access_token.expires_in:
+        # Calculate expiration time
+        issued_at = datetime.now(timezone.utc)


what's the purpose of this method? it's always going to be false because.

pcarleton · 2026-01-30T18:10:54Z

src/mcp/client/auth/extensions/enterprise_managed_auth.py

+        storage: TokenStorage,
+        idp_token_endpoint: str,
+        token_exchange_params: TokenExchangeParameters,
+        redirect_handler: Callable[[str], Awaitable[None]] | None = None,


does this class need a redirect handler and callback handler? since it's using ID-JAG there shouldn't be a redirect or callback

pcarleton · 2026-01-30T18:15:02Z

src/mcp/client/auth/extensions/enterprise_managed_auth.py

+        client_metadata: OAuthClientMetadata,
+        storage: TokenStorage,
+        idp_token_endpoint: str,
+        token_exchange_params: TokenExchangeParameters,


i think it's a bit awkward to take in TokenExchangeParameters here.

I think id_token_provider: Callable[[], Awaitable[str]], would be a good argument.

we also likely need idp_client_id / idp_client_secret as arguments.

I think it'd be good to rely on the existing mechanisms to get the resource URL and AS metadata, e.g.:

async def _perform_authorization(self) -> httpx.Request: audience = str(self.context.oauth_metadata.issuer) resource = self.context.get_resource_url() id_token = await self.id_token_provider() # Side request to IdP for token exchange (RFC 8693) id_jag = await self._exchange_for_id_jag(id_token, audience, resource) # Return JWT bearer grant request (RFC 7523) for base class to send return self._build_jwt_bearer_request(id_jag)

felixweinberger · 2026-01-30T21:13:46Z

pyproject.toml

    "dirty-equals>=0.9.0",
    "coverage[toml]>=7.10.7,<=7.13",
    "pillow>=12.0",
+    "fastapi>=0.115.0",  # For enterprise auth conformance test mock server


Can we not write the test without FastAPI? Seems like a heavy import for a test.

Kludex · 2026-01-31T08:50:41Z

This conformance tests is very cute in theory, but it's adding too much noise to the repository.

On another unrelated note, this kind of PR makes me extremely demotivated to continue to help this project. It's a 2.8k LOC, which none of the other maintainers seems to care.

I keep seeing auth related code, PRs, commits with bad coding practices, and being accepted just for the fear of the word "security", "compliance", "enterprise".

felixweinberger added auth Issues and PRs related to Authentication / OAuth enhancement Request for a new feature that's not currently supported labels Dec 9, 2025

maxisbey requested a review from pcarleton December 9, 2025 15:20

maxisbey requested changes Dec 9, 2025

View reviewed changes

maxisbey added the needs more work Not ready to be merged yet, needs additional follow-up from the author(s). label Dec 10, 2025

pcarleton mentioned this pull request Jan 14, 2026

Implement SEP-990 Enterprise Managed OAuth modelcontextprotocol/typescript-sdk#1328

Open

9 tasks

BinoyOza-okta added 18 commits January 30, 2026 17:12

- Implemented SEP-990 feature for providing support for Enterprise Ma…

9753ab2

…naged Auth support. - Written unit test cases for client and server implementation of the enterprise managed auth code.

Added test cases for missing lines of code.

a373a82

- Added tests cases for few of the missing lines. src/mcp/client/auth…

e4b2fb1

…/extensions/enterprise_managed_auth.py 232->235, 304->307. - Resolved pre-commit errors.

- Fixed pre-commit errors.

5a0b487

- Tried to fix the ruff error.

951fb55

- Fixed ruff errors.

49c9f24

- Removed server side changes for enterprise_managed_auth.py

ed2943a

- Added README.md changes for SEP-990 implementation for enterprise m…

053ac31

…anaged auth.

- Resolved pyright checks error.

defa7eb

- Resolved README.md file fixes for removing unused imports.

77f1aef

- Resolved pyright errors.

0e4f256

- Added new test cases for the missing code lines.

37dcc41

- Fixed the failing test cases.

b361f60

- Fixed the test cases.

a4f0c40

- Updated test case to include IDJAGClaims type model to verify payload.

a23abed

- Fix uv.lock.

b16b652

BinoyOza-okta force-pushed the feature/sep-990-enterprise-oauth branch from 8935a0f to b16b652 Compare January 30, 2026 16:24

pcarleton requested changes Jan 30, 2026

View reviewed changes

felixweinberger reviewed Jan 30, 2026

View reviewed changes

		print(f"Resource: {resource.uri}")


		async def maintain_active_session(

Implement SEP-990 Enterprise Managed OAuth #1721

Are you sure you want to change the base?

Implement SEP-990 Enterprise Managed OAuth #1721

Conversation

BinoyOza-okta commented Dec 4, 2025

Motivation and Context

Implementation Details

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

maxisbey left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BinoyOza-okta commented Dec 15, 2025

Uh oh!

pcarleton commented Jan 14, 2026

Uh oh!

BinoyOza-okta commented Jan 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kludex commented Jan 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants